home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / machserver / 1.098 / include / dev / RCS / pdev.h,v < prev   
Text File  |  1992-06-25  |  13KB  |  356 lines
  1. head     1.1;
  2. branch   ;
  3. access   ;
  4. symbols  srv018:1.1 srv008:1.1;
  5. locks    ; strict;
  6. comment  @ * @;
  7.  
  8.  
  9. 1.1
  10. date     91.11.17.18.30.28;  author kupfer;  state Exp;
  11. branches ;
  12. next     ;
  13.  
  14.  
  15. desc
  16. @@
  17.  
  18.  
  19.  
  20. 1.1
  21. log
  22. @Initial revision
  23. @
  24. text
  25. @/*
  26.  * pdev.h --
  27.  *
  28.  *    Declarations of the kernel/user-level-server interface for
  29.  *    pseudo-devices. A pseudo-device is a file
  30.  *    whose semantics are implemented by a user-level server process.
  31.  *    All other processes act on the file normally.  Their operations
  32.  *    on the file are mapped by the kernel into a request-response
  33.  *    exchange with the server process.  The types and constants defined
  34.  *    here are needed by the server programs to implement their
  35.  *    half of the pseudo-device protocol.  As well as implement the
  36.  *    regular file operations, Fs_Read, Fs_Write, and Fs_IOControl,
  37.  *    the server is involved in open/close time actions, and the
  38.  *    server helps control the select state of the pseudo device.
  39.  *    
  40.  *    A more complete explaination of pseudo-devices should be in
  41.  *    the man page (/sprite/doc/ref/devices/pdev), but the following
  42.  *    brief explaination may help.  The interface between the kernel
  43.  *    and the server process is based on filesystem streams.  The
  44.  *    server gets a "control stream" when it opens the pseudo-device
  45.  *    file with the FS_MASTER flag.  This control stream is readable
  46.  *    when a new client process has opened the pseudo-device.  The
  47.  *    control stream contains a short message with a new filesystem
  48.  *    streamID for a "service stream" that the server uses to communicate
  49.  *    with the new client.
  50.  *    Service streams are used by the server to get request messages
  51.  *    (that correspond to client operations) and return results.
  52.  *
  53.  *    Associated with each service stream is a "request buffer".  The server
  54.  *    gets request messages from clients indirectly; the requests are
  55.  *    placed into the request buffer, along with their data, and the server
  56.  *    learns about new requests by reading messages from the service stream
  57.  *    that contain 'firstByte' and 'lastByte' offsets into the request buffer.
  58.  *    This buffered interface lets the kernel stack up many requests (writes,
  59.  *    in particular) before a    context switch is required to the server
  60.  *    program.  Of course, this also lets the server handle all the queued
  61.  *    requests at one time.  When the    server has handled requests it updates
  62.  *    the 'firstByte' pointer by making a IOC_PDEV_SET_PTRS ioctl() on
  63.  *    the service stream.
  64.  *
  65.  *    There can also be a read ahead buffer associated with each service
  66.  *    stream.  This is filled with data by the server program that is to
  67.  *    be read by a client, and the kernel moves data from this buffer,
  68.  *    which is again in the server's address space, to the client without
  69.  *    having to switch out to the server process. 
  70.  *    
  71.  * Copyright 1987 Regents of the University of California
  72.  * All rights reserved.
  73.  * Permission to use, copy, modify, and distribute this
  74.  * software and its documentation for any purpose and without
  75.  * fee is hereby granted, provided that the above copyright
  76.  * notice appear in all copies.  The University of California
  77.  * makes no representations about the suitability of this
  78.  * software for any purpose.  It is provided "as is" without
  79.  * express or implied warranty.
  80.  *
  81.  *
  82.  * $Header: /sprite/src/lib/include/dev/RCS/pdev.h,v 1.17 89/06/15 12:15:06 brent Exp $ SPRITE (Berkeley)
  83.  */
  84.  
  85. #ifndef _PDEV
  86. #define _PDEV
  87.  
  88. #include "proc.h"
  89. #ifdef KERNEL
  90. #include "fs.h"
  91. #else
  92. #include <kernel/fs.h>
  93. #endif
  94.  
  95. /*
  96.  * Pseudo-device operations
  97.  *    PDEV_OPEN        The first request after a client open.
  98.  *    PDEV_DUP        OBSOLETE, but might resurrect itself.
  99.  *    PDEV_CLOSE        The last request.
  100.  *    PDEV_READ        Read data from the pseudo-device.
  101.  *    PDEV_WRITE        Write data to the pseudo-device.
  102.  *    PDEV_IOCTL        Special operation on the pseudo-device.
  103.  *    PDEV_WRITE_ASYNC    Asynchronous write.  No reply needed.
  104.  *
  105.  * These two only apply to pseudo-device connections to pseudo-file-systems.
  106.  * For regular pseudo-devices the kernel takes care of attribute handling.
  107.  *    PDEV_GET_ATTR        Get attributes given a pdev connection.
  108.  *    PDEV_SET_ATTR        Set attributes given a pdev connection.
  109.  */
  110.  
  111. typedef int Pdev_Op;
  112.  
  113. #define PDEV_OPEN        1
  114. /* #define PDEV_DUP        2 */
  115. #define PDEV_CLOSE        3
  116. #define PDEV_READ        4
  117. #define PDEV_WRITE        5
  118. #define PDEV_IOCTL        6
  119. #define PDEV_WRITE_ASYNC    7
  120. #define PDEV_GET_ATTR        8
  121. #define PDEV_SET_ATTR        9
  122.  
  123. /*
  124.  * A pseudo-device server gets a 'control stream' when opening a pseudo-device.
  125.  * The following structure describes the messages read from the control stream.
  126.  * Control stream messages are used to notify the server that it
  127.  * has a new private stream because a client opened the pseudo-device.
  128.  */
  129. typedef struct Pdev_Notify {
  130.     unsigned int    magic;            /* == PDEV_NOTIFY_MAGIC */
  131.     int            newStreamID;
  132.     int            reserved;        /* Extra */
  133. } Pdev_Notify;
  134.  
  135. #define PDEV_NOTIFY_MAGIC    0x1D4E4F52
  136.  
  137. /*
  138.  * The first message on a private stream is a PDEV_OPEN.
  139.  * This message identifies the client process, its host, and the host's
  140.  * byte order to the server.
  141.  */
  142.  
  143. typedef struct Pdev_OpenParam {
  144.     int flags;            /* Flags from the Fs_Open call */
  145.     Proc_PID pid;        /* Client's process ID */
  146.     int hostID;            /* Host ID where client is from */
  147.     int uid;            /* User ID of the client process */
  148.     int gid;            /* Group ID of the client process */
  149.     int byteOrder;        /* Byte order identifier */
  150.     int reserved;        /* Extra */
  151. } Pdev_OpenParam;
  152.  
  153. /*
  154.  * PDEV_READ, PDEV_WRITE request parameters, see <kernel/fsIO.h>
  155.  */
  156.  
  157. typedef Fs_IOParam Pdev_RWParam;
  158.  
  159. /*
  160.  * PDEV_IOCTL request parameter, see <kernel/fsIO.h>
  161.  */
  162.  
  163. typedef Fs_IOCParam Pdev_IOCParam;
  164.  
  165. /*
  166.  * PDEV_SET_ATTR request parameters.  These are in the Pdev_Request header,
  167.  * and the new Fs_Attributes record is passed as the data block following
  168.  * the header.  The user and group ID are used for authentication.
  169.  */
  170.  
  171. typedef struct {
  172.     int        flags;        /* Which attributes to set */
  173.     int        uid;        /* User ID */
  174.     int        gid;        /* Group ID */
  175. } Pdev_SetAttrParam;
  176.  
  177.  
  178. /*
  179.  * When a client does something to the pseudo-device the server gets
  180.  * a corresponding request message.  The structure of it is defined here.
  181.  * The control information in the request header is the same for both
  182.  * pseudo-device and pseudo-filesystem operations.
  183.  */
  184.  
  185. typedef struct {
  186.     unsigned int magic;        /* PDEV_REQUEST_MAGIC or PFS_REQUEST_MAGIC */
  187.     Pdev_Op    operation;    /* What action is requested. */
  188.     int        messageSize;    /* The complete size of the request header
  189.                  * plus data, plus padding for alignment */
  190.     int        requestSize;    /* Size of data following this header */
  191.     int        replySize;    /* Max size of the reply data expected. */
  192.     int        dataOffset;    /* Offset of data from start of header */
  193. } Pdev_RequestHdr;
  194.  
  195. typedef struct {
  196.     Pdev_RequestHdr    hdr;    /* with PDEV_REQUEST_MAGIC */
  197.     union {            /* Additional parameters to the operation. */
  198.     Pdev_OpenParam        open;
  199.     Pdev_RWParam        read;
  200.     Pdev_RWParam        write;
  201.     Pdev_IOCParam        ioctl;
  202.     Pdev_SetAttrParam    setAttr;
  203.     } param;
  204. } Pdev_Request;
  205.  
  206. #define PDEV_REQUEST_MAGIC    0x7265717E
  207.  
  208. /*
  209.  * IOC_PDEV_REPLY is used to return the following information about
  210.  * a reply to a client's request.  The status in
  211.  * the reply header will be the return value of the client's system call,
  212.  * except for FS_WOULD_BLOCK and FS_LOOKUP_REDIRECT which are processed
  213.  * by the kernel.
  214.  */
  215.  
  216. typedef struct Pdev_Reply {
  217.     unsigned int magic;        /* PDEV_REPLY_MAGIC */
  218.     ReturnStatus status;    /* Return status of remote call */
  219.     int        selectBits;    /* Return select state bits */
  220.     int        replySize;    /* Size of the data in replyBuf, if any */
  221.     Address    replyBuf;    /* Server space address of reply data */
  222.     int        signal;        /* Signal to return, if non-zero */
  223.     int        code;        /* Code to modify signal */
  224. } Pdev_Reply;
  225.  
  226. #define PDEV_REPLY_MAGIC    0x52455057
  227.  
  228. /*
  229.  * IOC_PDEV_SMALL_REPLY uses the following struct to return a small
  230.  * amount of data to the client's request.
  231.  * Up to PDEV_SMALL_DATA_LIMIT bytes can be returned.
  232.  * 
  233.  */
  234. #define PDEV_SMALL_DATA_LIMIT    16
  235.  
  236. typedef struct Pdev_ReplyData {
  237.     unsigned int magic;        /* PDEV_REPLY_DATA_MAGIC */
  238.     ReturnStatus status;    /* Return status of remote call */
  239.     int        selectBits;    /* Return select state bits */
  240.     int        replySize;    /* Size of following data */
  241.     Address    replyBuf;    /* Unused, needed for padding & compatibility */
  242.     int        signal;        /* (non-zero) Signal to generate, if any */
  243.     int        code;        /* Code to modify the signal */
  244.     char    data[PDEV_SMALL_DATA_LIMIT];    /* Reply data */
  245. } Pdev_ReplyData;
  246.  
  247. #define PDEV_REPLY_DATA_MAGIC    0x524ABC57
  248.  
  249. /*
  250.  * I/O Controls for server streams.
  251.  *    IOC_PDEV_READY        The server uses this to notify the kernel
  252.  *                that the pseudo-device is ready for I/O now.
  253.  *                The input buffer should contain an int
  254.  *                with an or'd combination of FS_READABLE,
  255.  *                FS_WRITABLE, or FS_EXCEPTION.
  256.  *    IOC_PDEV_SET_BUF    These are used to tell the kernel where the
  257.  *                request buffer and read ahead buffer (if any)
  258.  *                are. The input buffer should contain a
  259.  *                Pdev_SetBufArgs struct.  Note that this
  260.  *                needs to be done after getting a notification
  261.  *                on the control stream before any request
  262.  *                (i.e. the client's open request) comes through.
  263.  *                This can also be done later to change the
  264.  *                buffer if needed.  The buffer change takes
  265.  *                place as soon as the previous one empties.
  266.  *                The switch is indicated by the requestAddr
  267.  *                that you read from the service stream.
  268.  *    IOC_PDEV_WRITE_BEHIND    Set (Unset) write-behind buffering in the
  269.  *                request buffer.  The single input argument
  270.  *                is a pointer to a Boolean; TRUE enables
  271.  *                write-behind, FALSE inhibits it.  The default
  272.  *                is no write-behind.
  273.  *    IOC_PDEV_SET_PTRS    These are used to update the firstByte and
  274.  *                lastByte pointers into the request and
  275.  *                read ahead buffers.  The input buffer
  276.  *                is a Pdev_BufPtrs structure.
  277.  *    IOC_PDEV_REPLY        This is used to send a reply to a request.
  278.  *                The input buffer contains a Pdev_Reply.  This
  279.  *                includes an address (in the server's space)
  280.  *                of a buffer containing reply data, if any.
  281.  *    IOC_PDEV_SMALL_REPLY    This is like IOC_PDEV_REPLY, except that
  282.  *                the reply data is embedding in the struct
  283.  *                passed into the kernel.  The amount of data
  284.  *                that can be returned this was is defined
  285.  *                by PDEV_SMALL_DATA_LIMIT.
  286.  *    IOC_PDEV_BIG_WRITES    Set (Unset) the ability of the client to
  287.  *                write a chunk larger than will fit into
  288.  *                the request buffer.  This is to support
  289.  *                UDP socket semantics that prevent a client
  290.  *                from writing more than the declared packet size.
  291.  *                (Of course, we could do better by keeping the
  292.  *                 existing semantics that automatically break
  293.  *                 the write into smaller ones...)
  294.  *                The input buffer should reference a Boolean;
  295.  *                TRUE enables big writes (which is the default)
  296.  *                FALSE prevents big writes.
  297.  *    IOC_PDEV_SIGNAL_OWNER    This sends a signal to the controlling process
  298.  *                of the pseudo-device.  If there is no owner
  299.  *                then this is ignored.  The input buffer contains
  300.  *                the signal number and code to send.
  301.  *
  302.  */
  303.  
  304. #define IOC_PDEV        (2 << 16)
  305. #define IOC_PDEV_READY        (IOC_PDEV | 0x1)
  306. #define IOC_PDEV_SET_BUF    (IOC_PDEV | 0x2)
  307. #define IOC_PDEV_WRITE_BEHIND    (IOC_PDEV | 0x3)
  308. #define IOC_PDEV_SET_PTRS    (IOC_PDEV | 0x4)
  309. #define IOC_PDEV_REPLY        (IOC_PDEV | 0x5)
  310. #define IOC_PDEV_BIG_WRITES    (IOC_PDEV | 0x6)
  311. #define IOC_PDEV_SIGNAL_OWNER    (IOC_PDEV | 0x7)
  312. #define IOC_PDEV_SMALL_REPLY    (IOC_PDEV | 0x8)
  313.  
  314. /*
  315.  * Input structure for the IOC_PDEV_SET_BUF IOControl
  316.  */
  317.  
  318. typedef struct Pdev_SetBufArgs {
  319.     Address    requestBufAddr;        /* Server's address of request buffer */
  320.     int        requestBufSize;        /* Num bytes in the request buffer */
  321.     Address    readBufAddr;        /* NULL if no read ahead.  Non-NULL
  322.                      * implicitly enables read-ahead. */
  323.     int        readBufSize;        /* Num bytes in the read ahead buffer */
  324. } Pdev_SetBufArgs;
  325.  
  326. /*
  327.  * Input structure for IOC_PDEV_SET_PTRS IOControl.
  328.  */
  329.  
  330. typedef struct Pdev_BufPtrs {
  331.     int magic;            /* == PDEV_BUF_PTR_MAGIC */
  332.     Address    requestAddr;    /* The address of the request buffer.  This is
  333.                  * valid when reading only, and it indicates
  334.                  * what request buffer is being used.  See
  335.                  * IOC_PDEV_SET_BUF. */
  336.     int requestFirstByte;    /* Byte offset of the first valid data byte
  337.                  * in the request buffer.  If -1 buf is empty */
  338.     int requestLastByte;    /* Byte offset of the last valid data byte. */
  339.     int readFirstByte;        /* Byte offset of the first valid data byte
  340.                  * in the read ahead buffer. -1 => empty */
  341.     int readLastByte;        /* Byte offset of the last data byte. */
  342. } Pdev_BufPtrs;
  343.  
  344. #define PDEV_BUF_PTR_MAGIC    0x3C46DF14
  345.  
  346. /*
  347.  * Stucture for the IOC_PDEV_SIGNAL_OWNER operation.
  348.  */
  349. typedef struct Pdev_Signal {
  350.     unsigned int signal;
  351.     unsigned int code;
  352. } Pdev_Signal;
  353.  
  354. #endif _PDEV
  355. @
  356.